\subsection{Direct pss message with trojan chunk}

Pss has two fundamental types, a message and a trojan chunk structure which wraps the encrypted serialised message and contains a nonce that is mined to make the resulting chunk's content address (BMT hash) to match the targets.


\begin{definition}[Basic types: topic, targets, recipient, message and trojan]\label{def:pss-message}
\begin{lstlisting}[language=buzz1]
// /pss


define type topic        as [segment size]byte       // obfuscated topic matcher
define type targets      as [][]byte       // overlay prefixes 
define type recipient    as crypto/pubkey

// pss message
define type message 
    seal    segment            
    payload [!:4030]byte    // varlength padded to 4030B
    
// trojan chunk
define type trojan 
    nonce   segment           // the nonce to mine 
    message [4064]byte        // encrypted msg 
\end{lstlisting}
\end{definition}


The message is encoded in a way that allows integrity checking and at the same time obfuscates the topic. The operation to package the payload with a topic is called \emph{sealing}


\begin{definition}[Sealing/unsealing the message]\label{def:pss-sealing}
\begin{lstlisting}[language=buzz1]
// /pss

define function seal @payload []byte
    with topic
as
    @seal = hash @payload and @topic // obfuscate topic
        xor @topic          
    return message{ @seal, @payload }

define function unseal message
    with topic 
as
    @seal = hash @message payload and @topic 
    if @topic == @seal xor @message seal then // check 
        return @payload 
    return nil
    
\end{lstlisting}
\end{definition}

Functions \lstinline{wrap/unwrap} transform between message and trojan chunk. \lstinline{wrap} takes an optional recipient public key to asymmetrically encrypt the message.
The targets are a list of overlay address prefixes derived from overlay addresses of recipients, with length specified to guarantee that a chunk matching it will end up with the recipient solely as a result if  push-syncing.   

\begin{definition}[Wrapping/unwrapping]\label{def:wrap}
\begin{lstlisting}[language=buzz1]
// /pss

define function wrap message 
    for recipient
    to  targets
as 
    @msg = @message 
        (crypto/encrypt for @recipient if @recipient) 

    @nonce = crypto/mine @n such that
        @targets any is prefix of
            trojan{@n, @msg} as chunk address 
    trojan{@nonce, @msg} as chunk 

define function unwrap chunk
    for recipient
as
    @chunk bytes 
        (crypto/decrypt  for @recipient if @recipient)
            as message

\end{lstlisting}
\end{definition}

When a chunk arrives at the node,  \lstinline{pss/deliver} is called as a hook by the storage component.
First the message is unwrapped using the recipient private key and unsealed with all the topics API clients subscribed to. If the unsealing is successful, message integrity as well as topic matching is proven so the payload is written into the stream registered for the topic in question.

\begin{definition}[Incoming message handling]\label{def:delivery}
\begin{lstlisting}[language=buzz1]
// /pss

// mailbox is a handler type, expects payload
// sent sealed with the topic to be delivered via the stream 
define type mailbox
    topic
    deliveries stream of []byte 
    
define context mailboxes as []mailbox

define function deliver chunk
    @msg = @chunk unwrap for context recipient
    mailboxes each @mailbox 
        @payload = unseal @msg  with @mailbox topic
        if @payload then 
            write @msg payload 
                to @mailbox deliveries 
    

\end{lstlisting}
\end{definition}


\begin{definition}[pss API: send]\label{def:send}
\begin{lstlisting}[language=buzz1]
// /pss

define function send @payload []byte
    about topic
    for recipient
    ?to    targets
has api POST on "/pss/<recipient>/<topic>(?targets=<targets>)"
    with @payload as body
as 
    targets = lookup.targets for @recipient if no @targets
    context tag = tag/tag{}
    seal @payload with @topic        // seal with topic
        wrap for @recipient          // encrypt if given recipient
            to @targets              // mine nonce and returns trojan chunk
                store                // to be sent by push-sync
    return tag                       // tag to monitor status 
    
\end{lstlisting}
\end{definition}

\begin{definition}[pss API: receive]\label{def:receive}
\begin{lstlisting}[language=buzz1]
// /pss

define function receive about topic 
    on uint64 @channel
has api POST on "/pss/subscribe/<topic>(?on=<channel>)"
as 
    @stream = open @channel
    context mailboxes append= mailbox{ @topic, @stream }
    
define function cancel topic
    on @channel uint64
has api DELETE on "/pss/subscribe/<topic>(?on=<channel>)"
as
    context mailboxes any ch
\end{lstlisting}
\end{definition}

\subsection{Envelopes}

\begin{definition}[Envelope]\label{def:pss-envelope}
\begin{lstlisting}[language=buzz1]
// /pss

define type envelope
    id  [segment size]byte
    sig crypto/signature
    ps  postage/stamp   
    
\end{lstlisting}
\end{definition}
